---
sidebar_position: 1
---

import Image from "@theme/IdealImage";
import bundleSize from "./assets/bundle-size.png";
import rerenderVideo from "@site/static/videos/rerender-demo.mp4";
import scrollPerfVideo from "@site/static/videos/scroll-performance-demo.mp4";

# Principles

Flash Calendar was initially built for a Moni, a side project I built (no longer
available in the app stores). I saw a need for a fast and easy-to-customize
package that allowed me to build high-quality and polished date pickers.

The existing solutions at that time didn't cover my needs. The most popular one,
[`react-native-calendars`](https://github.com/wix/react-native-calendars) by
Wix, offerred great features, but there were a few things that bothered me: no
bottom sheet support, polish gaps (e.g. months with 6 and 5 weeks had
incosistent spacing between each other), bundle size (and extra dependencies
like `lodash`) and difficulty to customize.

After mantaining a patch for that library for more than 3 years, I decided to do
things differently this time and build my own solution.

The following are the guiding principles that helps me make decisions about the library.

## Solve fewer needs better

After working with `react-native-calendars`, I realized that library tried to do
too many things at once. Flash Calendar goes the opposite way. It offers an
elegant way of building calendars and calendars lists. Features like an agenda
mode are out of scope for this package.

## Fast

Flash Calendar, as the name implies, works at lightening speeds for the use
cases it was built for:

- infinite lists
- date picker
- date range picker

As such, it's heavily optimized to avoid unnecessary re-renders:

<video controls width={500}>
  <source src={rerenderVideo} type="video/mp4" />
</video>

From the video above, notice how **only the affected dates re-render**. This
means your component stays responsive no matter how lengthy the calendar list
is.

Besides re-render performance, it's also heavily optimized for scroll
performance, all thanks to the excellent
[FlashList](https://shopify.github.io/flash-list) foundation (kudos to
[Shopify](https://www.shopify.com/) for their incredible OSS work 🙏):

<video controls width={500}>
  <source src={scrollPerfVideo} type="video/mp4" />
</video>

Given the `<Calendar.List />` component is [just a
wrapper](https://github.com/marceloprado/flash-calendar/blob/06c813b26b2f4527b3eaacaddfa424df26d42e61/packages/flash-calendar/src/components/CalendarList.tsx#L266-L281)
around `FlashList`, it inherits all of its performance characteristics.
Additionally, all of FlashList's performance tuning guides apply to Flash
Calendar as well. You'll fell right at home.

Finally, Flash Calendar also honors this principle for local development.
Developing and writing tests for Flash Calendar should be so fast it makes you
smile - in fact, this was the key reason [Bun](https://bun.sh/) was chosen as
its test runner and [Turbo](https://turbo.build/) as its monorepo tool.

## Tiny footprint

I work for a large company. I know we're not willing to substantially increase
our bundle-size. In fact, we seize every oppotunity to decrease it.

Besides, most companies already have their preferred date formatting library.
Companies use `moment`, `date-fns`, `luxon`, `dayjs` and others. Flash Calendar
shouldn't make an assumption about a particular library - this would add
unnecessary bloat to every consumer. Flash Calendar allows you to **bring your
own date formatting library**, giving you full control over how dates are
formatted and localized.

As a result, the library weights just 18.8kb in size (**6kb gzip**), with a
[single 200 bytes](https://github.com/developit/mitt) external dependency:

<Image img={bundleSize} width={400} />

## Easy to use and customizable

With Flash Calendar, it's easy to do the right thing. The library offers a
simple and intuitive API, and give you full control over the look and feel of
your calendars.

Read the [Customization](/fundamentals/customization) section for more details.
